3D Graphics Programming with QuickDraw 3D 1.5.4

Previous | QD3D Book | Overview | Chapter Contents | Next |

Description

A metafile file pointer indicates the location of another object in that metafile, to which it points. A file pointer and the object to which it points (called the target object ) must occur in the same file. A target object may occur before or after an associated file pointer in a metafile. A file pointer may fail to have a target object; such a file pointer is null . File pointers may occur both in ASCII text metafiles and in binary metafiles. A file pointer is neither declared nor initialized; it is identified as such by the positions in which it may appear and (in a text file) by the type of expression used to represent it.

In a binary metafile, a file pointer is an unsigned 64-bit integer that specifies the address or location of its target object in the metafile. The generator of a binary metafile must determine the number of bytes by which the beginning of the target object is offset from the beginning of the header in order to write the correct value of a pointer to that object. (The beginning of the target object is the begining of its 4-byte type identifier.) A metafile generator must update that file pointer whenever any new objects are inserted between the beginning of the header and the beginning of the target object.

A file pointer is offset relative to the beginning of the 3DMF header of the metafile in which it occurs, not relative to the end of the header .

In an ASCII text metafile, a file pointer is represented by a character string composed of at least two characters, the last of which is a right angle bracket ( > ). Thus p> and Arrow> are file pointers; p , >, and Arrow are not. In a text file, the target object of a file pointer must bear a label corresponding to that file pointer. The label corresponding to a file pointer is the result of omitting the final right angle bracket from the string representing that file pointer. For example, the label corresponding to string5> is string5 . Such a label is always followed immediately by a colon and then, on a new line, by the target object:

string5: targetobject

Each file pointer may correspond to at most one label, and each label may correspond to at most one file pointer. Metafiles of type normal will typically contain labels that are not being pointed to by a file pointer, because the code that writes the metafile must write a label for every shared object. It must do this because it cannot predict whether the object about to be written will be written a second time (at which point it will be written as a reference and so will have to make use of a file pointer to that label).

Two types of file pointers may occur in a metafile, corresponding to two types of target object a file pointer may have. The target object of a file pointer of the first type is a table of contents; such a file pointer is meant to indicate the location of a table of contents and serves no other purpose. A file pointer of this type must occur in the fourth field of each header. A file pointer of this type must also occur in the first field of each table of contents; this pointer points to the location of the next subsequent table of contents, if one exists. A file pointer of this type may occur in no other position.

The target object of a file pointer of the second type must be either an object of type shared, or a container with root object of type shared. (To determine whether an object is of type shared, check its description in this document.) The root object of a container may not be the target object of a file pointer. The purpose of a file pointer of this type is to enable the metafile writer to make repeated reference to a target object without repeating that object's definition. (A file pointer of this type may occur only in the second field of a table of contents entry; thus, a metafile that contains file pointers of this type must include at least one table of contents.) The way in which repeated reference to an object is accomplished through the use of file pointers of this type is explained in the next paragraph.

An application may permit a user to make reference in one context to an object specified in another context. The 3DMF specification supports both reference to another object in the same metafile, and reference to an object in another metafile. We use the term external reference whenever we wish to talk about the second of these; the first is simply termed a reference . This section discusses references; external references are discussed in "External Reference Objects" .

A typical case of using references is to repeatedly use the same geometry but make it appear in different locations through appropriate uses of transforms (an example is given in "Examples of Metafile Structures" ). Another case is to apply the same texture shader to several different objects, or different faces of objects.

In a metafile, reference to objects involves several components: a file pointer, a target object, an integer, an entry in a table of contents, and a special metafile object called a reference object. (In a text file, the label that immediately precedes the object pointed to by the file pointer must also be present.) The object to be referenced must be the target object of a file pointer. That file pointer must appear together with an appropriately chosen integer, called a reference ID, in an entry in a table of contents located in the file containing the target object. (If that file contains no table of contents, then a table of contents must be created.) The reference ID associated with that file pointer must be the data of a reference object, one occurrence of which must be placed at each position at which the target object is to be referenced. In a text file, a reference object looks like this:

The target object, file pointer, table of contents, and reference object must all occur in the same file. There may be at most one file pointer to any target object; thus, once a reference ID has been associated with a pointer to a target object in a table of contents entry, that refID is the only integer that may be used to reference that target object. If a metafile contains a reference object with a reference ID that does not appear in the table of contents, then obviously the reference cannot be resolved and the read call on the reference object should return NULL . Many metafile readers would view this as an error in reading, so metafiles containing reference objects with unresolved refID values are regarded as incorrect.

Clearly, a metafile reader must be programmed to recognize and to respond appropriately to reference objects, tables of contents, file pointers (and perhaps labels) and not to confuse them with other types of objects. As noted, a metafile may contain file pointers and labels that are idle. A metafile reader cannot determine whether a file pointer or label is idle by inspection of that object alone, so it must be able to read these objects whether or not they're idle.

Example

Here is an example of the legal use of file pointers in an ASCII text metafile:

In this and other examples, the text metafile is followed by its equivalent binary metafile.

The file pointer line2> is used to place its target object within the scope of a Translate object; thus, it adds to the model a copy of the original line that's been transformed by a translation.